Basic4GL, Copyright (C) 2003 Tom Mulgrew
OpenGL guide
9-Nov-2003
Tom Mulgrew
This document will not teach you OpenGL!
Instead it is designed to give you the information you need to
use OpenGL tutorials and example programs from other sources in
Basic4GL.
One such source is Neon Helium Productions OpenGL tutorials http://nehe.gamedev.net.
Basic4GL conversions of tutorials 2 - 11 are available from the
"Programs" directory (named nehe2, nehe3, e.t.c).
The next important resource is an OpenGL function reference.
You can find one for the Microsoft Windows OpenGL implementation
at http://msdn.microsoft.com/library/default.asp
(Click and expand "Graphics and Multimedia" in the left
panel, and then "OpenGL". Expand "OpenGL",
"OpenGL Reference" then "GL Functions" for a
list of functions.)
Basic4GL supports version OpenGLv1.1, and supports all functions of the Win32 OpenGL implementation, except for:
Basic4GL also supports the following functions from the GL_ARB_multitexture extension:
The following glu funtions are supported:
Firstly, Basic4GL creates a window for you and initialises it
for OpenGL.
Therefore Basic4GL programs skip the initialisation stage and can
start executing OpenGL commands straight away.
Example:
glTranslatef (0, 0, -4)
glBegin (GL_TRIANGLES)
glColor3f (1, 0, 0): glVertex2f ( 0, 1)
glColor3f (0, 1, 0): glVertex2f (-1,-1)
glColor3f (0, 0, 1): glVertex2f ( 1,-1)
glEnd ()
SwapBuffers ()
Basic4GL also performs the following OpenGL calls at the beginning of each program:
Initialise the view port
glViewport (0, 0, WindowWidth(), WindowHeight())Create projection matrix, 60 degree field of view, near clip plane at 1, far clip plane at 1000
glMatrixMode (GL_PROJECTION)
glLoadIdentity ()
gluPerspective (60, (1.0*WindowWidth()) / WindowHeight(), 1, 1000)Initialise the model view matrix
glMatrixMode(GL_MODELVIEW)
glLoadIdentity()Enable depth testing
glEnable (GL_DEPTH_TEST)
glDepthFunc (GL_LEQUAL)
This is simply for convenience and saves typing - if you're
happy with the default settings.
Otherwise feel free to roll your own projection matrix e.t.c.
The WindowWidth() and WindowHeight() functions will return the
width and height of the output window. (Multiplying the
WindowWidth() by 1.0 simply converts it to a real value instead
of an integer, so that real division is used instead of integer).
The OpenGL window is double buffered.
This means it has a back buffer, which is hidden away from the user, and a front buffer which corresponds to the visible image on the screen.
All OpenGL rendering occurs in the back buffer. Once the scene
is complete and ready to be displayed it is "swapped"
to the front buffer, which displays it on the screen.
In Basic4GL you do this with the SwapBuffers() command.
SwapBuffers() will swap the completed scene from the back buffer. This immediately displays the result of the image that has just been rendered.
SwapBuffers() is a crucial part of any Basic4GL OpenGL program. Without it the user won't see anything rendered, because it will all be sitting in the back buffer, which is not displayed.
A simple example:
while true
glClearColor (rnd()%100/100.0, rnd()%100/100.0, rnd()%100/100.0, rnd()%100/100.0)
glClear (GL_COLOR_BUFFER_BIT)
SwapBuffers ()
wend
Will repeatedly clear the OpenGL window to a random colour,
and display it. The visual result is random flickering colours.
Without the SwapBuffers() call, the above program would not
appear to do anything, as nothing ever gets through to the front
buffer.
Note: SwapBuffers() will either copy the back buffer to the front buffer, or exchange the buffers. This appears to depend on the hardware, screen mode and OpenGL implementation. For example, my on NVidia GeForce2, SwapBuffers appears to exchange in fullscreen mode and copy in windowed mode.
Basic4GL uses the DevIL open-source image library to load image files, for use in OpenGL textures. Through DevIL Basic4GL supports Windows Bitmap files, Jpeg files and a host of other formats.
The DevIL library is distributed under the GNU LESSER GENERAL PUBLIC LICENSE Version 2.1 (See DevIL.txt), and is freely available from http://openil.sourceforge.net/.
Basic4GL uses DevIL image handles in place of (char *)
pointers to the pixel data.
For example, when calling glTexImage2D you pass in the image
handle as the last parameter in Basic4GL, whereas in C/C++ you
would pass in a pointer to the actual pixel data.
Basic4GL will substitute in a pointer to the pixel data
internally.
The easiest way to get a texture into Basic4GL is to use the
LoadTexture() and LoadMipmapTexture() functions.
Format:
Where x is a string containing the filename of an image to load into an OpenGL texture.
Both functions will allocate an OpenGL texture, load the image
into the texture, and return the OpenGL texture handle (a numeric
handle known as the "texture name").
The image files must be OpenGL friendly. That is their width and
height must be powers of 2.
LoadMipmapTexture will automatically build mipmaps for the
texture, and enable mipmapping for that texture.
LoadTexture does not build mipmaps, and will disable mipmapping
for the texture.
Both functions return 0, if for any reason they cannot load the image and store it in a texture.
Feel free to skip this section, if the above functions satisfy your needs.
The hands on method of loading textures involves loading them into images, and then uploading the images into textures.
The last parameter of glTexImage2D and gluBuild2DMipmaps has been changed to accept an image handle, instead of a pointer to the image data.
To obtain an image handle you need to use the Basic4GL image manipulation functions
LoadImage(x) will load an image into Basic4GL, but
does not upload it into OpenGL.
As with LoadTexture, x is a string containing the image
filename. The function returns an image handle representing the
image.
Currently there isn't much you can do with the image except upload it into OpenGL.
Once you've uploaded the image into an OpenGL texture, you're free to delete the image.
DeleteImage(x) will delete the image.
x is the image handle returned by LoadImage.
(Note: As with textures, Basic4GL tracks images and automatically deletes any undeleted ones after the program terminates.)
These functions are used to extract information about an
image.
They all accept an image handle from an earlier LoadImage call.
ImageDataType(x) returns the image data type.
Basic4GL automatically converts all images into GL_UNSIGNED_BYTE,
so ImageDataType will simply return that.
However this may change in future Basic4GL versions.
ImageFormat(x) returns the image format.
Currently Basic4GL automatically converts images into GL_RGB
format, so ImageFormat will simply return that.
Again this may change in future Basic4GL versions.
ImageHeight(x) returns the height of the image in pixels.
ImageWidth(x) returns the width of the image in pixels.
Example:
See the TextureDemo example program for different methods to load a texture in Basic4GL.
Basic4GL uses OpenGL v1.1.
Multitexturing is not natively part of the v1.1, but is available
through the OpenGL extensions mechanism.
Basic4GL automatically hooks into this extension and makes the associated functions and constants available to Basic4GL programs. (If the extension is not available, calling the functions will simply do nothing.)
The Basic4GL function ExtensionSupported is the easiest way to test whether the current hardware supports multitexturing, as for example:
if not ExtensionSupported ("GL_ARB_multitexture") then
Do something else...
(You can also check for other extensions, however this version of Basic4GL only supports GL_ARB_multitexture..)
This is exactly equivalent to calling glGetString (GL_EXTENSIONS) and testing the resulting string for the presence of "GL_ARB_multitexture"
MaxTextureUnits() will return the number of available texturing units.
dim units
units = MaxTextureUnits ()
Note: This is exactly equivalent to:
dim units
glGetIntegerv (GL_MAX_TEXTURE_UNITS_ARB, units)
These are the actual multitexturing functions that Basic4GL supports.
See the MultitextureDemo example program for an example of multitexturing in action.